Fix OpenType Context Substitution Format 3 and decomposition type handling for Arabic/emoji shaping by fjobeir · Pull Request #824 · opentypejs/opentype.js

fjobeir · 2026-04-01T11:34:39Z

Description

Replace the contextSubstitutionFormat3 implementation in src/features/featureQuery.mjs with one that uses lookupCoverageList and the standard lookup infrastructure (getLookupByIndex, getLookupMethod, getSubstitutionType) for proper GSUB lookup type 5, substFormat 3 handling. Additionally, fix both contextSubstitutionFormat3 and chainingSubstitutionFormat3 to use lookupRecord.sequenceIndex instead of iterating all input lookups, and add support for decomposition substitution type 21 in both functions.

Also adds a version field (1.4.0-beta.1) to package.json to support downstream dependency resolution.

Motivation and Context

Some Arabic fonts (e.g. IBM Plex Sans Arabic) use OpenType Context Substitution Format 3 (GSUB lookup type 5, substFormat 3) for contextual letter forms. The previous implementation bypassed the standard lookup infrastructure and could fail to correctly resolve substitutions. Additionally, both contextSubstitutionFormat3 and chainingSubstitutionFormat3 iterated all input lookups for each lookup record instead of targeting the specific glyph at sequenceIndex, causing duplicate glyph output. Fonts like noto-emoji that use nested decomposition substitution (type 21) within context/chaining lookups also failed because only type 12 was handled.

This is part of a broader effort to fix RTL (Arabic/Hebrew) text rendering in Next.js OG image generation, which uses Satori -> opentype.js for font shaping.

How Has This Been Tested?

All 328 existing tests pass (npm run test), including:
- featureQuery.mjs - "should parse multiple glyphs - ligature substitution format 3 (53)" — validates correct substitution output [54, 54]
- bidi.mjs - "shape emoji with sub_5" — validates flag emoji shaping produces [1850] (not [1850, 1850])
- featureQuery.mjs - "should find a substitute - chaining context substitution format 3 (63)" — validates chaining substitution still produces [1348]
Downstream Satori test suite (432 tests) passes with this change, including the Arabic language rendering test

Screenshots (if appropriate):

N/A — changes affect font shaping logic, validated via automated tests.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

I did npm run test and all tests passed green (including code styling checks).
I have added tests to cover my changes.
My change requires a change to the documentation.
I have updated the README accordingly.
I have read the Contribute README section.

Replace contextSubstitutionFormat3 with implementation that uses lookupCoverageList and getLookupByIndex for proper GSUB lookup type 5 substFormat 3 handling. Some Arabic fonts (e.g. IBM Plex Sans Arabic) use this lookup format for contextual letter forms. https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

Fix OpenType Context Substitution Format 3 for Arabic font shaping

Each lookupRecord should only substitute the glyph at its sequenceIndex, not iterate all input lookups. This caused duplicate results (e.g. [54,54,54,54] instead of [54,54]). https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

Fix contextSubstitutionFormat3 producing duplicate substitutions

The chaining context substitution handler only supported type '12' (single substitution format 2) and threw on all other types. Some fonts (e.g. noto-emoji) use type '21' (multiple/decomposition substitution) within chaining context lookups. https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

Handle decomposition substitution type 21 in chainingSubstitutionFormat3

Same fix as contextSubstitutionFormat3: each lookupRecord should only substitute the glyph at its sequenceIndex, not iterate all input lookups. Fixes duplicate glyph output in emoji/flag shaping. https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

Fix chainingSubstitutionFormat3 to use lookupRecord.sequenceIndex

Context substitution format 3 only handled nested lookup type '12' (single substitution). Some fonts (e.g. noto-emoji) use type '21' (multiple/decomposition substitution) in context substitution lookup records. Without handling type '21', the second covered glyph was not processed by the context substitution, causing it to be re-matched and duplicated in the ccmp pipeline. https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

Keep @shuding/opentype.js at 1.4.0-beta.0 (the published version). The opentype.js Context Substitution Format 3 fix is tracked separately in opentypejs/opentype.js#824. Restore webkit-text-stroke snapshots to match the published dependency. https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

fjobeir · 2026-04-08T08:39:26Z

Hi @fdb would you please take a look whenever possible

fdb · 2026-04-09T21:01:37Z

Hi @fjobeir, I looked at this. Some notes:

please don't commit the version number in package.json or a package-lock.json; we handle this separately. Once this is merged, I can make a new version you can use upstream.
We're missing tests for this PR. specifically it would be nice to have a font with OpenType Context Substitution Format 3 (GSUB lookup type 5, substFormat 3). I've tried validating with IBM Plex Sans Arabic (all weights, all formats, downloaded from Google Fonts as well as from https://github.com/IBM/plex) but the font doesn't actually use the structures this PR fixes:

it has no GSUB lookup type 5 (context substituion) lookups
all its type 6 (chaining context) subtables have inputCoverage.length === 1 with sequenceIndex: 0 so the old (buggy) loop produces the same results as the fixes.
In other words, the PR changes are a no-op for that font. Can you point me to a specific font where this fix changes the output or crashes opentype.js?

Ideally we have two things:

A minimal, synthetic test font that uses our raw font generation helpers (see test/generate-circular-ref-font.mjs for an example). This would then create a font with GSUB type 5, format 3 lookup with coverages.length >= 2 and lookupRecords with different sequenceIndex values, so we can assert the fix works:

// Pseudo-structure for the test font:
// - 5 glyphs: .notdef, A, B, A', B'
// - GSUB lookup type 5, format 3:
//     coverages: [covers A, covers B]        ← match A followed by B
//     lookupRecords:
//       { sequenceIndex: 0, lookupListIndex: 0 }  ← substitute A → A'
//       { sequenceIndex: 1, lookupListIndex: 1 }  ← substitute B → B'
// - Nested lookup 0: single sub A → A'
// - Nested lookup 1: single sub B → B'
//
// Input [A, B] should produce [A', B']
// The old bug would produce [A', B', A', B'] (iterating all inputs per record)

In addition, a real-world font that exercises this path, so we can validate against HarfBuzz and compare. If you have the font that triggered the crash in Satori/next.js OG, that would be great.

There are two ways you handle subtype 21: in chainingSubstitutionFormat3 you use a spread (substitutions.push(...substitution)) and in contextSubstitutionFormat3 you use a regular push (substitutions.push(substitution)). I think the non-spread version is the correct one, however now they accidentally yield the same result anyway.

// In chainingSubstitutionFormat3, change:
if (substitution) substitutions.push(...substitution);
// to:
if (substitution) substitutions.push(substitution);

Extension subtable handling in contextSubstitutionFormat3

The existing chainingSubstitutionFormat3 handles type '71' (extension subtables). These are wrappers that exist purely to allow 32-bit offsets in tables that would otherwise be limited to 16-bit, they don't change the substitution logic, they just redirect to the real subtable data. The existing code handles this by unwrapping subtable.extension before dispatch (lines 157-161 in the current code). Your rewritten contextSubstitutionFormat3 doesn't include this unwrapping, so fonts that use extension wrappers inside a context substitution format 3 lookup will silently fail.

Sorry for the long review, but GSUB is a tricky beast 😁 If you need any further help, lmk

- Remove version field from package.json (handled separately by maintainer) - Fix type 21 spread inconsistency: use substitutions.push(substitution) instead of push(...substitution) in chainingSubstitutionFormat3, matching contextSubstitutionFormat3 behavior - Add extension subtable (type 71) unwrapping in contextSubstitutionFormat3, matching existing chainingSubstitutionFormat3 pattern - Fix contextSubstitutionFormat3 to check each coverage against the glyph at its corresponding position instead of using lookupCoverageList (which only checks contextParams.current against all coverages) - Add synthetic test font with GSUB type 5 format 3 (context substitution) with coverages.length=2 and distinct sequenceIndex values, verifying: - [A, B] → [A', B'] produces correct output (not duplicated) - Short context returns empty - Non-matching glyphs return empty - Single lookupRecord only substitutes at its sequenceIndex https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

Address PR review feedback

Removed version '1.4.0-beta.1' from package-lock.json.

claude and others added 11 commits March 31, 2026 23:07

Merge pull request #1 from fjobeir/claude/fix-rtl-og-rendering-F7Kf7

0e6f156

Fix OpenType Context Substitution Format 3 for Arabic font shaping

Merge pull request #2 from fjobeir/claude/fix-rtl-og-rendering-F7Kf7

97cfeb8

Fix contextSubstitutionFormat3 producing duplicate substitutions

Update package-lock.json

b8f4a55

https://claude.ai/code/session_0192MAXgejpjkKBgChuyTFcd

Merge pull request #3 from fjobeir/claude/fix-rtl-og-rendering-F7Kf7

1267fe9

Handle decomposition substitution type 21 in chainingSubstitutionFormat3

Merge pull request #4 from fjobeir/claude/fix-rtl-og-rendering-F7Kf7

72c3d4d

Fix chainingSubstitutionFormat3 to use lookupRecord.sequenceIndex

Handle decomposition substitution type 21 in contextSubstitutionFormat3

ec7ba0c

fjobeir mentioned this pull request Apr 3, 2026

Fix RTL (Arabic/Hebrew) text rendering and layout fjobeir/satori#1

Merged

3 tasks

fjobeir mentioned this pull request Apr 3, 2026

feat: RTL (Arabic/Hebrew) text rendering and layout vercel/satori#745

Open

3 tasks

Merge branch 'master' into master

6d3714f

claude and others added 5 commits April 10, 2026 12:09

Merge pull request #6 from fjobeir/claude/fix-rtl-og-rendering-F7Kf7

e9fe29b

Address PR review feedback

fix: remove version from PR

478a12a

Remove version from package-lock.json

658d9c3

Removed version '1.4.0-beta.1' from package-lock.json.

reverse changes on package-lock.json

7b85ca3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix OpenType Context Substitution Format 3 and decomposition type handling for Arabic/emoji shaping#824

Fix OpenType Context Substitution Format 3 and decomposition type handling for Arabic/emoji shaping#824
fjobeir wants to merge 17 commits intoopentypejs:masterfrom
fjobeir:master

fjobeir commented Apr 1, 2026

Uh oh!

fjobeir commented Apr 8, 2026

Uh oh!

fdb commented Apr 9, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

fjobeir commented Apr 1, 2026

Description

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Checklist:

Uh oh!

fjobeir commented Apr 8, 2026

Uh oh!

fdb commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fdb commented Apr 9, 2026 •

edited

Loading